home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / GetCursor.3 < prev    next >
Encoding:
Text File  |  1994-09-20  |  10.1 KB  |  265 lines
  1.  
  2.  
  3.  
  4. Tk_GetCursor(3)       Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_GetCursor,     Tk_GetCursorFromData,     Tk_NameOfCursor,
  12.      Tk_FreeCursor - maintain database of cursors
  13.  
  14. SYNOPSIS
  15.      #include <tk.h>
  16.  
  17.      Cursor
  18.      Tk_GetCursor(_i_n_t_e_r_p, _t_k_w_i_n, _n_a_m_e_I_d)
  19.  
  20.      Cursor
  21.      Tk_GetCursorFromData(_i_n_t_e_r_p, _t_k_w_i_n, _s_o_u_r_c_e, _m_a_s_k, _w_i_d_t_h, _h_e_i_g_h_t, _x_H_o_t, _y_H_o_t, _f_g, _b_g)
  22.  
  23.      char *
  24.      Tk_NameOfCursor(_d_i_s_p_l_a_y, _c_u_r_s_o_r)                              |
  25.  
  26.      Tk_FreeCursor(_d_i_s_p_l_a_y, _c_u_r_s_o_r)                                |
  27.  
  28. ARGUMENTS
  29.      Tcl_Interp      *_i_n_t_e_r_p     (in)      Interpreter to use for
  30.                                            error reporting.
  31.  
  32.      Tk_Window       _t_k_w_i_n       (in)      Token  for  window  in
  33.                                            which  the cursor will
  34.                                            be used.
  35.  
  36.      Tk_Uid          _n_a_m_e_I_d      (in)      Description of cursor;
  37.                                            see below for possible
  38.                                            values.
  39.  
  40.      char            *_s_o_u_r_c_e     (in)      Data for  cursor  bit-
  41.                                            map,  in standard bit-
  42.                                            map format.
  43.  
  44.      char            *_m_a_s_k       (in)      Data for mask  bitmap,
  45.                                            in   standard   bitmap
  46.                                            format.
  47.  
  48.      unsigned int    _w_i_d_t_h       (in)      Width  of  _s_o_u_r_c_e  and
  49.                                            _m_a_s_k.
  50.  
  51.      unsigned int    _h_e_i_g_h_t      (in)      Height of  _s_o_u_r_c_e  and
  52.                                            _m_a_s_k.
  53.  
  54.      unsigned int    _x_H_o_t        (in)      X-location  of  cursor
  55.                                            hot-spot.
  56.  
  57.      unsigned int    _y_H_o_t        (in)      Y-location  of  cursor
  58.                                            hot-spot.
  59.  
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_GetCursor(3)       Tk Library Procedures
  71.  
  72.  
  73.  
  74.      Tk_Uid          _f_g          (in)      Textual description of
  75.                                            foreground  color  for
  76.                                            cursor.
  77.  
  78.      Tk_Uid          _b_g          (in)      Textual description of
  79.                                            background  color  for
  80.                                            cursor.
  81.  
  82.      Display         *_d_i_s_p_l_a_y    (in)      Display for which _c_u_r_-
  83.                                            _s_o_r was allocated.      |
  84.  
  85.      Cursor          _c_u_r_s_o_r      (in)      X identifier for  cur-
  86.                                            sor.      If    passed
  87.                                            toTk_FreeCursor,  must
  88.                                            have  been returned by
  89.                                            some previous call  to
  90.                                            Tk_GetCursor        or
  91.                                            Tk_GetCursorFromData.
  92. _________________________________________________________________
  93.  
  94.  
  95. DESCRIPTION
  96.      These procedures manage a collection of cursors  being  used
  97.      by  an  application.  The procedures allow cursors to be re-
  98.      used efficiently, thereby avoiding server overhead, and also
  99.      allow  cursors  to be named with character strings (actually
  100.      Tk_Uids).
  101.  
  102.      Tk_GetCursor takes as argument a Tk_Uid describing a cursor,
  103.      and  returns  the X identifier for a cursor corresponding to
  104.      the description.  It re-uses an existing cursor if  possible
  105.      and  creates a new one otherwise.  _N_a_m_e_I_d must be a standard
  106.      Tcl list with one of the following forms:
  107.  
  108.      _n_a_m_e  [_f_g_C_o_l_o_r  [_b_g_C_o_l_o_r]]
  109.           _N_a_m_e is the name of a cursor in the standard  X  cursor
  110.           font,  i.e.,  any of the names defined in cursorfont.h,
  111.           without the XC_.  Some  example  values  are  X_cursor,
  112.           hand2,  or left_ptr.  Appendix B of ``The X Window Sys-
  113.           tem'' by Scheifler & Gettys has  illustrations  showing
  114.           what  each of these cursors looks like.  If _f_g_C_o_l_o_r and
  115.           _b_g_C_o_l_o_r are both specified, they  give  the  foreground
  116.           and background colors to use for the cursor (any of the
  117.           forms acceptable to Tk_GetColor may be used).  If  only
  118.           _f_g_C_o_l_o_r  is specified, then there will be no background
  119.           color:  the background  will  be  transparent.   If  no
  120.           colors  are  specified,  then the cursor will use black
  121.           for its foreground color and white for  its  background
  122.           color.
  123.  
  124.      @_s_o_u_r_c_e_N_a_m_e  _m_a_s_k_N_a_m_e  _f_g_C_o_l_o_r  _b_g_C_o_l_o_r
  125.           In this form, _s_o_u_r_c_e_N_a_m_e and _m_a_s_k_N_a_m_e are the names  of
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tk_GetCursor(3)       Tk Library Procedures
  137.  
  138.  
  139.  
  140.           files  describing  bitmaps for the cursor's source bits
  141.           and mask.  Each file must be in  standard  X11  or  X10
  142.           bitmap format.  _F_g_C_o_l_o_r and _b_g_C_o_l_o_r indicate the colors
  143.           to use for the cursor, in any of the  forms  acceptable
  144.           to Tk_GetColor.
  145.  
  146.      @_s_o_u_r_c_e_N_a_m_e  _f_g_C_o_l_o_r
  147.           This form is similar to the one above, except that  the
  148.           source  is  used  as  mask  also.   This means that the
  149.           cursor's background is transparent.
  150.  
  151.      Tk_GetCursorFromData allows cursors to be created  from  in-
  152.      memory  descriptions  of  their  source  and  mask  bitmaps.
  153.      _S_o_u_r_c_e points to  standard  bitmap  data  for  the  cursor's
  154.      source  bits,  and  _m_a_s_k  points  to  standard  bitmap  data
  155.      describing which pixels of _s_o_u_r_c_e are to be drawn and  which
  156.      are to be considered transparent.  _W_i_d_t_h and _h_e_i_g_h_t give the
  157.      dimensions of the cursor, _x_H_o_t and _y_H_o_t indicate  the  loca-
  158.      tion  of  the  cursor's hot-spot (the point that is reported
  159.      when an event occurs), and _f_g and _b_g describe  the  cursor's
  160.      foreground and background colors textually (any of the forms
  161.      suitable for Tk_GetColor may be used).  Typically, the argu-
  162.      ments  to  Tk_GetCursorFromData  are  created by including a
  163.      cursor file directly into the source code for a program,  as
  164.      in the following example:
  165.           Cursor cursor;
  166.           #include "source.cursor"
  167.           #include "mask.cursor"
  168.           cursor = Tk_GetCursorFromData(interp, tkwin, source_bits,
  169.                           mask_bits, source_width, source_height, source_x_hot,
  170.                           source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue"));
  171.  
  172.      Under     normal      conditions,      Tk_GetCursor      and
  173.      Tk_GetCursorFromData  will  return  an  identifier  for  the
  174.      requested cursor.  If an error occurs in creating  the  cur-
  175.      sor, such as when _n_a_m_e_I_d refers to a non-existent file, then
  176.      None is returned and an error  message  will  be  stored  in
  177.      _i_n_t_e_r_p->_r_e_s_u_l_t.
  178.  
  179.      Tk_GetCursor and Tk_GetCursorFromData maintain a database of
  180.      all  the  cursors  they  have created.  Whenever possible, a
  181.      call to Tk_GetCursor or Tk_GetCursorFromData will return  an
  182.      existing  cursor  rather  than  creating  a  new  one.  This
  183.      approach can substantially reduce server overhead, so the Tk
  184.      procedures  should  generally  be used in preference to Xlib
  185.      procedures like  XCreateFontCursor  or  XCreatePixmapCursor,
  186.      which create a new cursor on each call.
  187.  
  188.      The procedure Tk_NameOfCursor  is  roughly  the  inverse  of
  189.      Tk_GetCursor.    If  its  _c_u_r_s_o_r  argument  was  created  by
  190.      Tk_GetCursor, then the return value is the  _n_a_m_e_I_d  argument
  191.      that  was  passed  to Tk_GetCursor to create the cursor.  If
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Tk_GetCursor(3)       Tk Library Procedures
  203.  
  204.  
  205.  
  206.      _c_u_r_s_o_r was created by a call to Tk_GetCursorFromData, or  by
  207.      any  other mechanism, then the return value is a hexadecimal
  208.      string giving the X identifier for the cursor.   Note:   the
  209.      string  returned  by  Tk_NameOfCursor  is only guaranteed to
  210.      persist until the next call to Tk_NameOfCursor.
  211.  
  212.      When    a    cursor    returned    by    Tk_GetCursor     or
  213.      Tk_GetCursorFromData  is  no  longer  needed,  Tk_FreeCursor
  214.      should be called to release it.  There should be exactly one
  215.      call  to  Tk_FreeCursor  for  each  call  to Tk_GetCursor or
  216.      Tk_GetCursorFromData.  When a cursor is  no  longer  in  use
  217.      anywhere  (i.e.  it  has  been freed as many times as it has
  218.      been gotten) Tk_FreeCursor will release it to the  X  server
  219.      and remove it from the database.
  220.  
  221.  
  222. BUGS
  223.      In determining whether an existing cursor  can  be  used  to
  224.      satisfy a new request, Tk_GetCursor and Tk_GetCursorFromData
  225.      consider only the immediate values of their arguments.   For
  226.      example,  when  a  file  name  is  passed  to  Tk_GetCursor,
  227.      Tk_GetCursor will assume it is safe to  re-use  an  existing
  228.      cursor  created  from the same file name:  it will not check
  229.      to see whether the file itself has changed, or  whether  the
  230.      current  directory  has changed, thereby causing the name to
  231.      refer to a different file.  Similarly,  Tk_GetCursorFromData
  232.      assumes  that if the same _s_o_u_r_c_e pointer is used in two dif-
  233.      ferent calls, then the pointers refer to the same data;   it
  234.      does  not  check  to  see  if  the  actual  data values have
  235.      changed.
  236.  
  237.  
  238. KEYWORDS
  239.      cursor
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Tk                                                              4
  262.  
  263.  
  264.  
  265.